                      ***************************
                     *       Locksmith 6.0        *
                     *  Documentation by Mr. Wiz  *
                      ***************************

System requirements:
Apple II, Apple II+, Apple //e, Apple //c, or compatible.
48K RAM and 1 disk drive minimum.
Optional RAM - 16K, 32K, 48K, 64K, 128K, 256K.

Common Locksmith Control Keys:
-----------------------------
These keys can be typed at any time while in Locksmith.

CTRL-Z - Will print text screen to printer.  Printer slot assumed to be in slot 1, but may be changed by parameter PRT.SLOT.

ESC - Will abort current function and return to an earlier menu.  Repeated pressing will return to main menu.

RESET - Will exit Locksmith and reboot system.

Note: Locksmith (LS) uses extensive memory overlays while performing tasks.  Keep the LS disk in the boot drive until instructed to remove it.

The top 7 lines of the display show the status of the current operation.  Tracks are number 0-23 (hex) corresponding to 0-36 (decimal).  Quarter tracks are also allowed.

Main Menu:
---------
Booting the LS disk will result in the main menu appearing.  The body of this menu displays the keystrokes (inverse) which you enter to perform certain functions.  Briefly, they are:

(B) BACKUP/COPY - Backup protected software using LS standard copy functions.

(F) FAST BACKUP - Quickly create copies of unprotected software.  Will utilize all additional memory in the computer for a copy process taking as little as 8 seconds.

(/) CLR STATUS - Clears the track status display at the top of the screen.

(N) DISK EDITOR - Formerly, the Nibble Editor.  Allows manual reading, searching, changing, etc. of data in a sector format or nibble format.  Can also be used to edit data in RAM.

(L) LOAD RAM CD - Will load slot 0 RAM with 12K of data found on tracks 12, 13 and 14 (hex) of LS disk.  Useful for loading Inspector or Watson.  Pressing I will invoke these functions once they are in memory.

(*) PARAMETERS - Allows display and changing of curent LS operating parameters by name.

(T) TEXT EDITOR - Used to edit files containing LS Programming Language (LPL), which can be loaded and saved on the parameters disk.  The BACKUP function allows automatic backup of protected software after specifying the name of the software.

(R) RAMCD UTILS - Can be used to test RAM cards in your Apple.  Will test any size cards, and two tests are provided: a basic test and an extensive test.  The test can be performed continuously or just once to help isolate intermittent errors.  In addition, the contents of any 16K bank of the RAM card can be dumped to main memory, edited with the disk editor and re-loaded to RAM cards.

(Q) SCAN DISK - Allows you to examine on the hi-res screen an overall "picture" of the disk, track by track.  This is useful in determining which tracks are actually used.

(A) BOOT TRACER - A sophisticated debugger which can simulate the operation of the 6502 in the Apple.  Because disk reading is simulated, it is possible to actually "boot" a disk (whether protected or not) under control of the debugger and trace the boot code of the program.

(C) CERTIFY DISK - Writes a special pattern to each track of a disk and verifies the integrety of the disk surface.

(U) 16-S UTILS - Brings up a second menu of 16 sector utilities.

(D) DOS3.3 UTIL - Brings up a second menu of DOS 3.3 utilities.

(X) DSK RECOVER - Will read a difficult or impossible to read disk and write a good copy to another disk.  Useful in transferring disks that were written in an improperly aligned machine.

(S) DISK SPEED - Allows speed adjustment of disk drives.

(E) ERASE DISK - Will partially or completely erase a disk.

(I) INSPECTOR - Invokes Inspector or Watson utilities if loaded with the "L" menu item.

Backup/Copy Disk:
----------------
Pressing 'B' will invoke the standard default copy method for copying protected disks.  This will work with most protected software.

Pressing 'F' will invoke the high-speed copy process.  This only works for unprotected software and utilizes as much memory as you have available.  The following commands are used in Fast Backup:
     12   Copy drive 1 to drive 2
     21   Copy drive 2 to drive 1
     11   Copy to and from drive 1
     22   Copy to and from drive 2
     1    Read verify drive 1
     2    Read verify drive 2
     10   Copy drive 1 to memory
     20   Copy drive 2 to memory
     01   Copy memory to drive 1
     02   Copy memory to drive 2
     V    Toggle verify flag after each operation
(SPACE or RETURN) to start operation
In addition to these commands there are several parameters which can be modified to allow read and write sector oriented protected disks, and set internal parameters.  The following parameters apply:

0007=00 Requested output volume # or 0, if same as input volume.

0008=00 Begin track to process.

0009=22 End track to process.

0010=08 Maximum read retry count. Retry number is 1-9 for first 9 revolutions of disk, A-Z for next 26.  After that the display will not change.

0011=03 Maximum verify after write retry.

0012=10 Motor On delay for read. 7F maximum.

0013=10 Motor On delay for write. Maximum is 7F.

0014=80 Seek Off delay to read. DOS uses FF, the longest value. A delay of 00 is satisfactory and will reduce overall copy time by about 1 second.

0015=80 Seek Off delay for write.  Do not change to any number less than 80 or drive may begin writing before the seek mechanism has settled.

0016=0B Number of self-sync before address field, expressed in excess-5 notation.  The default value will write 16 self-sync nibbles and the value of 01 will write 6 self-sync nibbles.  Setting this value very low will cause over-writing of the subsequent address field, too high will not allow all 16 sectors to fit on a disk.

0017=08 Number of self-sync before data field. (See 0016.)

0018=00 Alternate writing to drive 1 and 2.  Setting to FF will cause alternate writing between 2 drives allowing very fast and efficient disk copying and use of memory.

To change any parameter, enter the 4-digit address and press RETURN.  The current value will be displayed, enter a new value if you wish to change it.

Clear Track Status Display:
--------------------------
The track status display is not cleared after each LS function.  Pressing '/' will manually clear this display.

Disk, Nibble, and Memory Editor:
-------------------------------
Pressing 'N' will enter the Disk Editor (formerly Nibble Editor).

Cursor Movement-I,J,K,M diamond or arrow keys on //e or //c. '<' and '>' will page forwards and backwards through memory. ',' and '.' will scroll continuously through the buffer.

Display Control-'A' will toggle ASCII display on/off.  'B' will toggle between byte and nibble modes.  In nibble mode, self-sync bytes are inverse.

Control Keys-CTRL-R will read a track into buffer. CTRL-W will write track from buffer to disk.  (IF NO ANALYSIS WAS DONE TO TRACK TO SET TRACK START AND END, LS WILL ATTEMP TO WRITE ENTIRE BUFFER.)  CTRL-V will verify track start.  Place cursor over nibble you wish to start verification process.  CTRL-I will insert nibbles into the current buffer starting to the right of the nibble your cursor is on.  CTRL-D will delete nibbles.  CTRL-F will find a pattern of nibbles.  Pressing RETURN will search for string defined in parameter PATO, 'L' will prompt you for a length (1-F).  CTRL-B moves cursor to track start, CTRL-E to track end.  '(' sets track start to current cursor, ')' sets track end.  'S' sets nibble under cursor to self-sync, 'N' sets nibble to normal.  'C' enters change mode.  'H' will display buffer on hi-res screen, 'HG' will print hi-res screen if your printer is capable of graphics output.  The printer initialization string is defined in parm GR.CHARS.  'G' from text mode will display a picture of buffer using text characters. A period (.) means all nibbles in string are normal, an inverse (#) means self-sync, (+) means a combination of normal and self-sync. 'D' is the 16 sector address decode command.  The first 4 numbers are the buffer address, next is the letter 'V' with a hex number (the volume), a two digit number with (/) another 2 digit number for track/sector.  Following that is either '?', 'CS', or '**'.  A '?' means either the check sum or trailer are incorrect.  'CS' means data field check sum is incorrect. '**' means data field info is incorrect or the disk is 13 sector.  Pressing '#' prints the current track in the bufferfrom '(' to ')'.  CTRL-S will process the analysis portion of the current track procedure used after reading to analyze the nibble data and set pointers for later writing.

Framing Bit Analyzer:
--------------------
     Framing bits (sync bits or timing bits) are the zero bits which occur between nibbles of data on the disk.  These nibbles are called self-sync bytes.  16 sector disks use 10-bit self sync or 2 framing bits.  The analyzer performs statistical analysis using precise timing loops and reports the timing relationship of the nibble data.  The analyzer is entered by pressing '$' from the disk editor and reading in a track.
     An example:  Get into the disk editor and CTRL-R to read a track of nibbles.  Place the start '(' pointer to the start of the address field (D5 AA 96).  Move the cursor down about 10 lines and set the end pointer ')'. Now move the cursor back up to the DE AA after the start of the address field.
     The analyzer uses the data from the start pointer to the nibble immediately before the cursor as a "key".  If you placed '(' before the D5 nibble and the cursor on the DE nibble, the key length would be $0B nibbles.
     Enter the analyzer by pressing '$'.  The display shows the data being analyzed on the left with statistics on the right.
     The following commands control the framing analyzer:
     SPACE temporarily stops so you can examine statistics.
     RETURN start again.
     < and > allow scrolling.
     T switches from nibble to timing stats.
The info on the right of the screen might look like the following:
        R=0007
        F=07
            ??
          --  ++
        0   02
        1 00  25
        2 25  03
        3 02  00
        4 01  01
        5 00  18
        6 0B  00
        7 00  07
        8   03
The R= value is the number of reads which occurred.  The F= value is the number of reads in which the "key" of the data was found on the track.  Because of limited buffer space, if a large data length is specified, it is possible that the buffer may not fully contain the data specified.
     The table of numbers represents the count of the differences of the data read with the "ideal" values of 10, 20, 30, etc.  These error diferences range from -7 to +7, with 00 being ideal.  For example, in the table above, the count for +1 is 25 (hex).  This means that there are 25 occurrences of nibbles with timing values of one greater than the ideal value (11, 21, 31, etc.).  The "8" count of 03 indicates 3 occurrences of timing values exactly halfway between ideal values.  This indicates that more examples are needed.  The "??" is displayed when the values for the +- 6,7, and 8 counts are non-zero, and indicates that more examples are needed.
     When nibble data is displayed on the left side, the inverse/normal mode of each nibble indicates the number of framing bits after the nibble.  Normal text indicates no framing bits.  Both digits are inverse if 2 framing bits while only one digit means 1 framing bit.  A flashing value is 3 or more framing bits.
     If the nibble data has the high order bit turned off, this indicates that at least one read occurred where the data after the key did not match.  This could have been caused by a loss of sync while reading or by the key being specified as too short which caused a non-unique part of the track to be analyzed instead of the desired part.

Load RAM Card:
-------------
     Pressing 'L' from the main menu will cause tracks $12, $13, and $14 to be read into memory addresses $D000-$FFFF of a RAM card in slot 0 (or the top 16K of a 64K //e or //c).
     If you have Inspector or Watson you can load it into RAM as follows:
1. Boot Inspector or Watson.
2. Enter Inspector or Watson, insert your LS disk and press the following:
    B D 0 <return>
    T 1 2 <return>
    CTRL-W
3. Then press CTRL-I 15 times.
This will write Inspector or Watson you your LS disk.
     Your LS disk normally contains a copy of Integer Basic and the monitor on tracks $13 and $14.  Inspector/Watson will go on track $12.

Parameters:
----------
     Pressing '*' will allow display and modification of parameters using their LS Programming Language variable names.  To display the value of a parameter, enter the keyword "SHOW" followed by the parm name.  For example, to display the current value of the parameter SLOT, enter SHOW SLOT. To change the value, enter the parm name and new value, SLOT 4.  If you make an error, LS will beep and ignore your request.
     The following patch is useful in reading sectors from a disk that reads unreliably.  This patch to RWTS will defeat the head recalibration routine after an I/O error and try to read again:  BDCC 4C C1 BD.  To reset the normal value, use  BDCC 10 F3 AD.  To restore parms to their original values, just rebot LS.

Backup Using Custom Parameters:
------------------------------
     The text editor function is used to automatically select a parameter file to be used to back up a disk.  To enter this function, press 'N' for NEW (clears the buffer) followed by 'B' for Backup.
     If the parm disk is not in the drive, you will be prompted to insert it.  A list of directory entries will be displayed.  Move the "light bar" using the arrow keys to the proper selection (or CTRL-K, CTRL-J).  CTRL-N and CTRL-P will move by pages.  If you know the name, just type the first letter to find the proper selection quickly.  Pressing RETURN will enter your selection.

Loading A Parameter File:
------------------------
     Pressing 'L' will prompt you to load a parm file from the parm disk.  Follow the directions under Backup Using Custom Parms.

Saving A Parameter File:
-----------------------
     'S' will save a parameter file to the parm disk.  You may create your own, or transfer one from one disk to another.

New - Create Edit Work Area:
---------------------------
     'N' will clear the text editor and start a new parm file entry.

Text Editor:
-----------
     To enter the text editor, press 'E'.  ESC will exit the text editor and return to the edit menu.  'N' clears the text editor for a NEW file.
     The text editor is a line numbered editor.  All lines entered are given sequential line numbers, which are displayed in inverse on the left of the screen.  Line numbers are displayed in hex, and only those referring to a portion of a file with the ".I" directive refer to LPL (Locksmith Programming Language).
     Lines are displayed one line at a line with 2 positions for the line number and 38 positions for the entry (40 characters).  If it is necessary to continue an LPL statement on anothr line, the minus (-) sign as the last character of the first line is needed.
     There are 2 cursors used in the editor.  If the line number is flashing, the cursor is on the line.  If a single character is flashing, the cursor is within the line at the cursor position.  This is important for insert and delete operations.  Characters can be inserted at the current cursor position with CTRL-I, CTRL-D will delete characters.
     Use 'X' for Syntax Checking after you have entered your text.

RAM Card Utilities:
------------------
     RAM card utilties are selected with 'R'.  They are self-explanatory and include a helpful RAM card test feature as well as being able to dump the contents of the ram card to and from main memory 16K at a time to locations 2000-5FFF as follows:
          2000-2FFF RAM card pages D0-DF alternate
          3000-3FFF    "       "   D0-DF
          4000-4FFF    "       "   E0-EF
          5000-5FFF    "       "   F0-FF

Scan Disk:
---------
     'Q' will help you to determine what tracks are in use on a disk you are trying to copy.  This utility will scan a disk for valid data.  The display is hi-res and runs from bottom to top of the screen.  The first time you run ths utility, you should use a normal DOS 3.3 disk for comparison purposes.  First try tracks 0-22 in whole increments.  This will show what a normal good disk looks like.  The series of dots above each track number are the gaps of self sync bytes between each sector.  Normally, on a 16 sector disk there will be 16-17 of these dots.  A 13 sector disk will have 13-14 dots.  On a 16 sector disk, one of the dots will be a little longer than the others, relating to self sync bytes before track 0.  You will notice that the dots will either move up or down as you move from track to track.  This is due to the time it takes to move the disk drive head from track to track.
     Now try scanning from .5 to 22.5 in increments of 1.  You will see very long white lines with no particular pattern.  This means there is no valid data on that track.  Some evidence of valid data such as short bursts of dots is cross-talk between adjacent half tracks.
     Spiral tracking or 1/4 tracking will show as a long band of white with a pattern of black between the white.

Automatic Boot Tracer:
---------------------
     The Automatic Boot Tracer (ABT) is intended for the more experienced Apple programmer, but may be the greatest utility on the LS disk.  It essentially simulates the 6502 processor in your Apple in a very slow speed so you can boot trace disks, copy protected or not.
     Pressing 'A' invokes the ABT function and requires a RAM card of at least 16K to work.  The upper 16K in a //e or //c works fine.  LS will prompt you for the slot of your RAM card, normally you select 0.  ABT will be installed and then entered.  (ABT will sometimes be called the simulator or debugger in this discussion.)
     The screen will clear and an inverse line of text will appear on the top of the screen indicating ABT is now operating.  Pressing <reset> now will enter the ABT and you can boot a disk with 6CTRL-P. Unfortunately, a disk that boots into the RAM card area will destroy the simulator function.

Information Line:
     The top line in inverse normally starts out as:
     FA62  CLD       A=00 X=00 Y=00 P=34 S=FD
The first 4 characters are the program counter address followed by the opcode to be executed.  Next are the A, X, and Y registers, the processor status register contents and the value of the stack pointer.
     At this time press 'R' followed by any key from A to X.  This moves the inverse status line to another location on the screen.  Y or Z will move the line off the screen.

Idle Mode:
     The simulator is in idle mode at this time.  The progam is running but all activity has ceased at the address shown.
     Press CTRL-C at this time to enable the 65C02 instructions, especially if you have the enhanced //e or //c.
     The 'S' key will start execution under control of the simuator.  The ABT is now running.  The display will rapidly change as the boot is started.  The "beep" you hear from the speaker will be slightly different than the normal Apple beep.
     To stop the simulator, press CTRL-Z putting you into the idle mode.  This is the normal stop key but can be changed if you need CTRL-Z in your program.  To change it, stop the program with CTRL-Z, press CTRL-X followed by whatever key you want to assign to the stop function.
     Enter the idle mode and press SPACE to single step the program.  A "+" or "-" will appear after each conditional branch depending on whether or not the branch will be taken (+) or not (-).
     While in idle mode, CTRL-Y will place you in the monitor where you can use 'L' to disassemble the code.  To reenter the simulator, pess CTRL-Y <RETURN>.  Before placing you in the monitor, the simulator saved low memory pages 00 to 07 in the RAM card.  After reentering the simulator, this memory was refreshed, insuring that no memory was changed.
     Other idle mode commands are:
        T - Trace subroutine until a JSR or RTS is fetched.
   CTRL-R - Cause a simulated reset to occur. The program counter
            is fetched from $FFFC.
   CTRL-I - Causes a simulated IRQ interrupt.
   CTRL-F - Turns off IRQ pending flag.
   CTRL-N - Causes simulated NMI interrupt.
   CTRL-Q - Quit simulator and go to monitor.
        1 - Set single-cycle mode, using SPACE to cycle one 6502
            processor cycle at a time, instead of an entire
            instruction.
        0 - Set instruction mode, valid only when on an instruction
            boundary (not in the middle of an instruction).
        B - Toggle beep flag on/off.
        C - Toggle click flag on/off.
   CTRL-C - Toggle 65C02 flag on/off.
        K - Take next keypress and place it in the keyboard register.
            When instruction stepping throuhg code that reads the
            keyboard, this key allows a way to enter a keyboard
            command without entering run mode.
      ESC - Enter simulator menu.

Simulator Control Window:
     Press ESC while in the idle mode.  The simulator control window is displayed, and the cursor appears in the upper left of the window.
     Use the RETURN key, and the left and right arrows to move the cursor around the window.  To change data anywhere, position the cursor over the value to change, enter the change.  To exit and return to idle mode, press ESC again.  CTRL-C will cancel any changes you made.
     The top line of the simulator control window appears very much like the idle mode window, except the program counter is more to the right and no instruction is disassembled.  The number on the left is used for single byte reading, writing, and memory editing.  Enter a number followed by 'R' to read, 'W' to write, and 'E' to edit.
     To change display modes for the simulated program (text, graphics, hi-res, lo-res, page1, page2, fullscreen, mixed) key in the address to toggle ($C050-$C057) and enter 'R'.  When tracing a program in graphics mode, place the information line on rows U, V, W, or X and toggle mixed text-graphics mode.
     To edit, enter 'E' and the memory is displayed in both hex and ASCII text.  Move the cursor with the arrows and RETURN.
     The second line of the window contains: 
         RU=65   0=I 1=I 2=I 3=S 4=I 5=I 6=D 7=I
"RU=65" (decimal 101) is the register update value, representing the number of instructions that are simulated before the registers and program counter are updated on the screen, when in "running" mode.  If the number is set too small, the registers will be updated after every instruction.  This causes the simulator to run less efficiently, because of overhead involved in updating the information line.

Slot Specifications:
     The rest of the second line displays the slot numbers and how they are to be used.  Because the simulator resides on a RAM board (indicated by 'S' in the slot display for "SYSTEM"), it must know about all other RAM boards and firmware boards if it is to correctly simulate their operation.  Initially, these locations are set to 'I' (INVALID).  Any reference to these invalid slots will cause the simulated program to stop and control is passed to idle mode.  Valid slot specification values are:
        S - system (simulator) slot
        I - invalid
        D - floppy disk drive
        A - RAM card of 16K or 32K
        B - RAM card of 64K or more
        F - Firmware card or ROM card
        T - transparent
If the specification for a slot is "transparent", any commands for the device in that slot will be given without checking or conversion by the simulator.  Transparent mode should be used for:
     Any devices such as RAM or ROM cards that bank select memory
     into addresses $D000-$FFFF, which is used by the simulator.

     Any devices such as disk drives which are timing dependent.

     Any devices which use direct memory access to modify memory
     from addresses $0000-$07FF, as this memory is used by the
     simulator.

Address Compare Stop:
     The third line of the simulator window starting with "PC" is the "PC compare stop" line.  Up to 4 program counter values for "compare stop" can be specified.  If the simulated program's PC equals one of these values, the simulator immediately enters idle mode.  In addition, one compare stop range can be specified.  To enter program counter stop values or a range, cnage th number (initially 0) to the number of stop addresses to be entered and then enter the address.  To cancel, reenter 0.
     The "MR" line is the "memory read address compare stop" line.  Again, up to 4 stops and 1 memory range can be set.  Whenever the simulated program attempts to read one of these addresses, either by direct addressing, indirect addressing, or stack fetch, the simulator will enter idle.
     The "MW" line is the "memory write address compare stop" line.  It follows the same conventions as the MR line.

END OF LOCKSMITH 6.0 DOCS - PART 1 of 2 PARTS